// Copyright (C) 2010, 2011, Steffen Knollmann
// Released under the terms of the GNU General Public License version 3.
// This file is part of `ginnungagap'.

#ifndef G9PWN_H
#define G9PWN_H


/*--- Doxygen file description ------------------------------------------*/

/**
 * @file g9pWN.h
 * @ingroup  ginnungagapWN
 * @brief  Provides the interface to the WN routines.
 */


/*--- Includes ----------------------------------------------------------*/
#include "g9pConfig.h"
#include "../libutil/parse_ini.h"
#include "../libgrid/gridRegular.h"


/*--- ADT handle --------------------------------------------------------*/
typedef struct g9pWN_struct *g9pWN_t;


/*--- Prototypes of exported functions ----------------------------------*/

/**
 * @brief  Creates a new WN module from an ini file.
 *
 * @param[in,out]  ini
 *                    The ini file that should be parsed.
 * @param[in]      *sectionName
 *                    The section name in which to look for the
 *                    construction information.
 *
 * @return  Returns a new WN module.
 */
extern g9pWN_t
g9pWN_newFromIni(parse_ini_t ini, const char *sectionName);

extern void
g9pWN_del(g9pWN_t *wn);

extern void
g9pWN_setup(g9pWN_t       wn,
            gridRegular_t grid,
            int           idxOfDensVar);

extern void
g9pWN_dump(g9pWN_t wn, gridRegular_t grid);

extern void
g9pWN_reset(g9pWN_t wn);


/*--- Doxygen group definitions -----------------------------------------*/

/**
 * @defgroup ginnungagapWN  White Noise
 * @ingroup ginnungagap
 * @brief Provides the WN functionality.

 * @section ginnungagapWNIniFormat  Expected Format of [WhiteNoise]
 *
 * @code
 * [WhiteNoise]
 * #
 * #################
 * # Required keys #
 * #################
 * #
 * # Selects whether the white noise is read from a file or whether it
 * # should be generated by an RNG.
 * useFile = <true|false>
 * #
 * # Selects whether the white noise is written to a file or not.
 * dumpWhiteNoise = <true|false>
 * #
 * @endcode
 *
 * Depending on the values of the two key, different sets of keys are
 * the required.  If the white noise has to be generate from an RNG, the
 * section should look like this:
 *
 * @code
 * #
 * # Not using a file, but rather a RNG.
 * useFile = false
 * #
 * # The name of the section in the ini file in which the construction
 * # information for the RNG can be found. 
 * rngSectionName = <string>
 * #
 * @endcode
 *
 * To see how the RNG is constructed, see @ref libutilMiscRNGIniFormat.
 *
 * If instead a file should be used, then the section should look
 * instead like this:
 *
 * @code
 * #
 * # Using a file.
 * useFile = true
 * #
 * # The section from which to construct the reader.
 * readerSection = <string>
 * #
 * @endcode
 *
 * The reader construction actually happens outside of this scope in
 * gridReader_newFromIni(), see @ref libgridIOInIniFormat for the
 * details.
 *
 * The other required key, <tt>dumpWhiteNoise</tt>, only requires more
 * parameters, if it is @c true.  In that case, the following structure
 * should be available in the section:
 *
 * @code
 * #
 * # Writing the White Noise to a file
 * dumpWhiteNoise = true
 * #
 * # The section in which to look for the construction information of
 * # the writer.
 * writerSection = <string>
 * #
 * @endcode
 *
 * The writer construction again happens outside of this scope in
 * gridWriter_newFromIni(), see @ref libgridIOOutIniFormat for the
 * details.
 *
 * For clarity, here are two examples of possible <tt>[WhiteNoise]</tt>
 * section.  This first one would be for a completely file backed
 * WhiteNoise, it is read and written:
 *
 * @code
 * [WhiteNoise]
 * useFile = true
 * readerSection = <string>
 * dumpWhiteNoise = true
 * writerSection = <string>
 * @endcode
 *
 * The second example uses a RNG to create the white noise field and
 * then writes it to a file.
 *
 * @code
 * [WhiteNoise]
 * useFile = false
 * rngSectionName = <string>
 * dumpWhiteNoise = true
 * writerSection = <string>
 * @endcode
 */


#endif
